home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / gate / Gate.man < prev    next >
Text File  |  1992-06-05  |  3KB  |  107 lines
  1. '\" Copyright 1992 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/lib/forms/RCS/lib.man,v 1.4 92/03/02 15:25:36 bmiller Exp $ SPRITE (Berkeley)
  10. '/" 
  11. .so \*(]ltmac.sprite
  12. .HS Gate lib
  13. .BS
  14. '\" Note:  do not modify the .SH NAME line immediately below!
  15. .SH NAME
  16. Gate_ByDesc, Gate_ByInetAddr, Gate_ByNetAddr, Gate_End, Gate_Next, Gate_SetFile,
  17. Gate_Start \- return information about network gateways.
  18. .SH SYNOPSIS
  19. .nf
  20. \fB#include <gate.h>\fR
  21. .sp
  22. Gate_Entry *
  23. \fBGate_ByDesc\fR(\fIdesc\fP)
  24. .sp
  25. Gate_Entry *
  26. \fBGate_ByInetAddr\fR(\fIinetAddr\fP)
  27. .sp
  28. Gate_Entry *
  29. \fBGate_ByNetAddr\fR(\fIaddrPtr\fP)
  30. .sp
  31. int
  32. \fBGate_SetFile\fR(\fIfileName\fP)
  33. .sp
  34. int
  35. \fBGate_Start\fR()
  36. .sp
  37. Gate_Entry *
  38. \fBGate_Next\fR()
  39. .sp
  40. void
  41. \fBGate_End\fR()
  42. .SH ARGUMENTS
  43. .AS Net_InetAddress inetAddr
  44. .AP char *desc in
  45. Description of the gateway for which information is desired.
  46. .AP Net_Address *addrPtr in
  47. The local network address of the gateway for which
  48. information is desired. 
  49. .AP Net_InetAddress inetAddr in
  50. The internet address of the gateway for which information is desired.
  51. .AP char *fileName in
  52. The name of a gateway description file.
  53. .BE
  54.  
  55. .SH DESCRIPTION
  56. .PP
  57. These functions are used to access the database of network gateways.
  58. .PP
  59. A Gate_Entry structure is defined as follows:
  60. .DS
  61. .ta 1c 2c 3c 4c 5c 6c 7c 8c 9c 10c
  62. typedef struct Gate_Entry {
  63.     char            *desc;        /* Description of gateway */
  64.     Net_Address        netAddr;    /* Physical address. */
  65.     Net_InetAddress    inetAddr;    /* Internet address. */
  66. } Gate_Entry;
  67. .DE
  68. The Gate_Entry structures returned by the routines are statically allocated
  69. and may change on the next call to any \fBGate_\fR procedure.  Be sure to copy
  70. out any information you need before calling a \fBGate_\fR procedure again.
  71. .PP
  72. \fBGate_ByDesc()\fR returns a Gate_Entry based on the description (name) of
  73. the gateway. 
  74. .PP
  75. \fBGate_ByNetAddr()\fR returns the Gate_Entry for the gateway with the given
  76. local-area-network address. 
  77. .PP
  78. \fBGate_ByInetAddr()\fR returns the Gate_Entry for the gateway with the given internet
  79. address.
  80. .PP
  81. \fBGate_SetFile()\fR specifies a different gateway information
  82. file to use (the file normally used
  83. is \fB/etc/gateway\fR).
  84. .PP
  85. \fBGate_Start()\fR opens the current gateway-description file (if it isn't
  86. already open), while \fBGate_End()\fR closes
  87. it.  The \fBGate_By\fR... procedures automatically call \fBGate_Start\fR.
  88. .PP
  89. \fBGate_Next()\fR may be used to step through the current 
  90. gateway-description file.
  91. The gateway-description file must have been opened 
  92. using \fBGate_Start()\fR or one of the
  93. \fBGate_By\fR functions.
  94. .PP
  95. .SH DIAGNOSTICS
  96. \fBGate_SetFile()\fR and \fBGate_Start()\fR 
  97. return zero if all went well.  Otherwise
  98. they return -1 and the \fBerrno\fR variable contains additional information
  99. about what error occurred.
  100. \fBGate_Next()\fR returns NULL on end-of-file. \fBGate_ByDesc()\fR,
  101. \fBGate_ByNetAddr()\fR and \fBGate_ByInetAddr()\fR return NULL if
  102. the given gateway could not be found.
  103. .SH FILES
  104. /etc/gateway    The default gateway-description file.
  105. .SH KEYWORDS
  106. internet, local net, gateway
  107.